home *** CD-ROM | disk | FTP | other *** search
/ Personal Computer World 2009 February / PCWFEB09.iso / Software / Linux / SLAX 6.0.8 / slax-6.0.8.iso / slax / base / 006-devel.lzm / usr / include / kreverseresolver.h < prev    next >
Encoding:
C/C++ Source or Header  |  2006-01-19  |  6.4 KB  |  196 lines
  1. /*  -*- C++ -*-
  2.  *  Copyright (C) 2003 Thiago Macieira <thiago.macieira@kdemail.net>
  3.  *
  4.  *
  5.  *  Permission is hereby granted, free of charge, to any person obtaining
  6.  *  a copy of this software and associated documentation files (the
  7.  *  "Software"), to deal in the Software without restriction, including
  8.  *  without limitation the rights to use, copy, modify, merge, publish,
  9.  *  distribute, sublicense, and/or sell copies of the Software, and to
  10.  *  permit persons to whom the Software is furnished to do so, subject to
  11.  *  the following conditions:
  12.  *
  13.  *  The above copyright notice and this permission notice shall be included 
  14.  *  in all copies or substantial portions of the Software.
  15.  *
  16.  *  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
  17.  *  EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
  18.  *  MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
  19.  *  NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
  20.  *  LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
  21.  *  OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
  22.  *  WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  23.  */
  24.  
  25. #ifndef KREVERSERESOLVER_H
  26. #define KREVERSERESOLVER_H
  27.  
  28. //////////////////
  29. // Needed includes
  30. #include <qobject.h>
  31. #include <qstring.h>
  32.  
  33. #include "ksocketaddress.h"
  34.  
  35. namespace KNetwork {
  36.  
  37. class KReverseResolverPrivate;
  38. /** @class KReverseResolver kreverseresolver.h kreverseresolver.h
  39.  *  @brief Run a reverse-resolution on a socket address.
  40.  *
  41.  * This class is provided as a counterpart to KResolver in such a way
  42.  * as it produces a reverse resolution: it resolves a socket address
  43.  * from its binary representations into a textual representation.
  44.  *
  45.  * Most users will use the static functions @ref resolve, which work
  46.  * both synchronously (blocking) and asynchronously (non-blocking).
  47.  *
  48.  * @author Thiago Macieira <thiago.macieira@kdemail.net>
  49.  */
  50. class KDECORE_EXPORT KReverseResolver: public QObject
  51. {
  52.   Q_OBJECT
  53.  
  54. public:
  55.   /**
  56.    * Flags for the reverse resolution.
  57.    *
  58.    * These flags are used by the reverse resolution functions for
  59.    * setting resolution parameters. The possible values are:
  60.    * @li NumericHost: don't try to resolve the host address to a text form.
  61.    *        Instead, convert the address to its numeric textual representation.
  62.    * @li NumericService: the same as NumericHost, but for the service name
  63.    * @li NodeNameOnly: returns the node name only (i.e., not the Fully
  64.    *        Qualified Domain Name)
  65.    * @li Datagram: in case of ambiguity in the service name, prefer the
  66.    *        name associated with the datagram protocol
  67.    * @li NumericScope: for those addresses which have the concept of scope,
  68.    *            resolve using the numeric value instead of the proper scope name.
  69.    * @li ResolutionRequired: normally, when resolving, if the name resolution
  70.    *            fails, the process normally converts the numeric address into its
  71.    *            presentation forms. This flag causes the function to return
  72.    *            with error instead.
  73.    */
  74.   enum Flags
  75.     {
  76.       NumericHost = 0x01,
  77.       NumericService = 0x02,
  78.       NodeNameOnly = 0x04,
  79.       Datagram = 0x08,
  80.       NumericScope = 0x10,
  81.       ResolutionRequired = 0x20
  82.     };
  83.  
  84.   /**
  85.    * Constructs this object to resolve the given socket address.
  86.    *
  87.    * @param addr    the address to resolve
  88.    * @param flags    the flags to use, see @ref Flags
  89.    */
  90.   KReverseResolver(const KSocketAddress& addr, int flags = 0,
  91.            QObject * = 0L, const char * = 0L);
  92.  
  93.   /**
  94.    * Destructor.
  95.    */
  96.   virtual ~KReverseResolver();
  97.  
  98.   /**
  99.    * This function returns 'true' if the processing is still running.
  100.    */
  101.   bool isRunning() const;
  102.  
  103.   /**
  104.    * This function returns true if the processing has finished with
  105.    * success, false if it's still running or failed.
  106.    */
  107.   bool success() const;
  108.  
  109.   /**
  110.    * This function returns true if the processing has finished with
  111.    * failure, false if it's still running or succeeded.
  112.    */
  113.   bool failure() const;
  114.  
  115.   /**
  116.    * Returns the resolved node name, if the resolution has finished 
  117.    * successfully, or QString::null otherwise.
  118.    */
  119.   QString node() const;
  120.  
  121.   /**
  122.    * Returns the resolved service name, if the resolution has finished
  123.    * successfully, or QString::null otherwise.
  124.    */
  125.   QString service() const;
  126.  
  127.   /**
  128.    * Returns the socket address which was subject to resolution.
  129.    */
  130.   const KSocketAddress& address() const;
  131.  
  132.   /**
  133.    * Starts the resolution. This function returns 'true'
  134.    * if the resolution has started successfully.
  135.    */
  136.   bool start();
  137.  
  138.   /**
  139.    * Overrides event handling
  140.    */
  141.   virtual bool event(QEvent* );
  142.  
  143. signals:
  144.   /**
  145.    * This signal is emitted when the resolution has finished.
  146.    *
  147.    * @param obj        this class, which contains the results
  148.    */
  149.   void finished(const KReverseResolver& obj);
  150.  
  151. public:
  152.   /**
  153.    * Resolves a socket address to its textual representation
  154.    *
  155.    * FIXME!! How can we do this in a non-blocking manner!?
  156.    *
  157.    * This function is used to resolve a socket address from its
  158.    * binary representation to a textual form, even if numeric only.
  159.    *
  160.    * @param addr    the socket address to be resolved
  161.    * @param node    the QString where we will store the resolved node
  162.    * @param serv    the QString where we will store the resolved service
  163.    * @param flags    flags to be used for this resolution.
  164.    * @return true if the resolution succeeded, false if not
  165.    * @see ReverseFlags for the possible values for @p flags
  166.    */
  167.   static bool resolve(const KSocketAddress& addr, QString& node, 
  168.               QString& serv, int flags = 0);
  169.  
  170.   /**
  171.    * Resolves a socket address to its textual representation
  172.    *
  173.    * FIXME!! How can we do this in a non-blocking manner!?
  174.    *
  175.    * This function behaves just like the above one, except it takes
  176.    * a sockaddr structure and its size as parameters.
  177.    *
  178.    * @param sa    the sockaddr structure containing the address to be resolved
  179.    * @param salen    the length of the sockaddr structure
  180.    * @param node    the QString where we will store the resolved node
  181.    * @param serv    the QString where we will store the resolved service
  182.    * @param flags    flags to be used for this resolution.
  183.    * @return true if the resolution succeeded, false if not
  184.    * @see ReverseFlags for the possible values for @p flags
  185.    */
  186.   static bool resolve(const struct sockaddr* sa, Q_UINT16 salen, 
  187.               QString& node, QString& serv, int flags = 0);
  188.  
  189. private:
  190.   KReverseResolverPrivate* d;
  191. };
  192.  
  193. }                // namespace KNetwork
  194.  
  195. #endif
  196.